Gatsby - How to setup a blog 🚀

February 17, 2021

What Is Gatsby?

Gatsby or GatsbyJS is a framework based on React library and GraphQL that makes it easy to create both website and web applications.

It is built on the Jamstack – a strategy for building websites/apps based on client-side JavaScript (or other scripts), reusable APIs and prebuilt Markup. This type of site has high performance, scalability and safety.

Though, Gatsby is considered a static site generator (SSG) like other Jamstack technologies (Jekyll, Next, Hugo etc) based on what it shares with them. But in reality, it can do much more than you can typically do with a static site generator.

You can think of Gatsby as a React framework for building complex websites and web apps. With Gatsbyjs, you are not limited to static sites. You can build a blog site, e-commerce or any complex website by using the latest tools like React, GraphQL, headless CMSs etc.

Initial Setup

To get started with Gatsby, you will need to have NodeJS and Git installed on your machine. With NodeJS, you can run your Gatsby JavaScript code outside of a web browser. You will also have access to its npm (node package manager) tool.

You can check if you have it installed by running npm -v and node –v in your terminal. The commands should return their respective versions. If not, head over to NodeJS website, download and install the latest version.

Gatsby allows us to start a project by using any of its starter template. There are many built-in templates officially released by the Gatsby team. Likewise, there are hundreds of other once that are created by third-party developers.

With these templates, you can create all sort of interesting sites and applications.

The goal here is to explore the fundamental features, a Gatsby starter is used with the minimum feature – i.e no plugins and no boilerplate.

How to create a Blog with Gatsby ? 🤔

👉 creating a blog with Gatsby and deploying it on Netlify

The convention to install a new Gatsby starter through the CLI is:

gatsby new [PROJECT_DIRECTORY] [STARTER_URL]

Gatsby Starter Templates

Gatsby Starter Templates

👉 Gatsby Starter Blog template has the following features—

  • SEO
  • Category Tags
  • Tag pages
  • Dark/Light modes

Prerequisites

npm / yarn
git / github

React (not needed if you want to use the template as it is) Let's get started Create a new repository on GitHub and clone it locally.

git clone  https://github.com/your-username/your-blog
cd your-blog

Install the gatsby CLI

npm install -g gatsby-cli

Create a new site using the starter site into app directory

gatsby new app https://github.com/ihsavru/gatsby-starter-peach

Move the contents of the app directory to the root directory.

mv app/* .
rm -rf app

🛑 👉 Before we take a look inside the project folder, let's run the development server. To do this, we will run one of the scripts that Gatsby provides. If you open the package.json file in the root and check the scripts property, you will see something like this:

"scripts": {
  "build": "gatsby build",
  "develop": "gatsby develop",
  "format": "prettier --write \"**/*.{js,jsx,json,md}\"",
  "start": "npm run develop",
  "serve": "gatsby serve",
  "clean": "gatsby clean",
  "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\" && exit 1"
},

👉 Your focus here should be on the develop script. This will allow you to start the development server and build your project locally. This script also comes with live reload so that changes are reflected in real time.

👉 You can start your Gatsby site either from your computer terminal or the integrated terminal of VsCode (if you are using it). From the computer terminal, navigate into your project directory:

Development

Run the development server.

gatsby develop

You can make any changes you want and it will be reflected on http://localhost:8000/

Open site-meta-data.json and edit the fields accordingly. You might have to restart your development server to see these changes being reflected. (You can skip these changes and edit later using Netlify CMS after deploying)

Next open static/admin/config.yml and change iren/gatsby-starter-blog to your repo.

👉 create a .gitignore file

Add the code below 👇

node_modules
public
.cache
.DS_Store

After you are done, commit your changes and push it to GitHub.

git add .
git commit -m "your commit message here"
git push

Inside the Project Directory

Having worked with React, I you should be familiar with the project (folders and files) structure, but I will quickly touch some of the important folders and files.

👉 The node_modules folder contains all the third-party libraries as well as Gatsby itself. This directory will also contain packages you’ll be installing through npm later in the tutorial. The public folder will contain the public asset of your site and will hold your static files.

👉 The src folder will contain all of your working files. This is where you’ll spend most of your time. Inside this folder, we have the pages directory. This is a very important directory inside the Gatsby project. Any files inside this folder automatically become static pages with paths based on their filename.

At the moment, we have index.js present in the pages folder. And as you know, the index file always references the home page. This is why the content of this file is being rendered in the frontend.

👉 The gatsby-config.js file is where you configure your Gatsby site. In this file, you set the site title, description, the Gatsby plugins to include and some other configuration.

👉 The package.jsoncontains information about your site. It has some dependencies of libraries that are currently installed and if you install other packages, they will be listed as well.

👉 The src/pages folder holds the file for the site static pages. 👉 Go inside the folder and open the index.js file. The code in this file is a simple React component that is rendering a simple "Hello world!" on the screen.

Working With Gatsby Pages

The focus will be on the src/pages directory. At the moment, we only have the index.js file in this folder.

When it comes to page creation, this directory is where Gatsby looks when it is figuring out what static pages your site needs. So all the files you put inside this directory will represent your site pages.

So let’s get started with the index.js file. 

import React from "react"

const Index = () => {
  return (
    <div>
      <h1>Home page</h1>
      <h2>I am Irene, a teacher and a web developer</h2>
    </div>
  )
}

export default Index

Generating the files

It starts by looking at the src/pages folder to figure out which static pages it should create. In our case, it realizes we only have one file, index.js. Meaning our site will only have a single page.

Now the name of the file is also important. Here, the file is called index.js. This is similar to how index.html will be the default page for a website homepage.

👉 Gatsby, index.js will be the default homepage. To create a new page, all you have to do is to add a new file to the src/pages directory.

Deployment

👉 Create an account on Netlify

After logging in, go to Sites

👉 click on "New Site from git"

Complete the following steps - Connect to GitHub, select your repository and deploy site.

Set build command to gatsby build and publish directory to public.

Start creating your Posts

Go to your deployed Netlify site and go to the Admin page - https://your-site.netlify.app/admin Log in using GitHub.

Now you can edit your blogs as well as your site metadata from here itself! You can delete the sample blogs that come with the template and add your own.

Go to Starter Files Code 👇

Sample Starter Blog

Up next